Document the background knowledge, the intention and not the result
You should write what the class/method does, not how it does it.
{@link MyClass#someMethod} should be written the first time someMethod is mentioned in the text. Subsequent mentions should not have links.
Generally use @link, @see and @seealso generously.
Purpose
Description (optional)
Purpose
Description (optional)
Statement whether this class implements an entity or a process defined by a standard specification
Statement whether instances of this class are mutable (optional).
Statement whether this class is multi-threading safe (optional).
Purpose
Expected effect
Description (optional)
Statement whether this method is modal (optional).
Required parameters. It must be explicitly stated whether null is permitted as a parameter value.
Per default parameters are assumed to require a non-null value and to cause a IllegalArgumentException if null is given.
Exceptions that can be thrown in the course of method's execution and their possible cause (post-conditions).
Private methods can have minimal or no JavaDocs if they are short and trivial enough.
Methods that implement a signature from an interface or base class that is sufficiently documented there can omit JavaDocs